home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 039a / jpsrc2.zip / SETUP < prev    next >
Text File  |  1991-12-13  |  12KB  |  236 lines
  1. SETUP instructions for the Independent JPEG Group's JPEG software
  2. =================================================================
  3.  
  4. This file explains how to configure and compile the JPEG software.  We have
  5. tried to make this software extremely portable and flexible, so that it can be
  6. adapted to almost any environment.  The downside of this decision is that the
  7. installation process is not very automatic; you will need at least a little
  8. familiarity with C programming and program build procedures for your system.
  9.  
  10. This file contains general instructions, then sections of specific hints for
  11. certain systems.  You may save yourself considerable time if you scan the
  12. whole file before starting to do anything.
  13.  
  14. Before installing the software you must unpack the distributed source code.
  15. Since you are reading this file, you have probably already succeeded in this
  16. task.  However, there is one potential trap if you are on a non-Unix system:
  17. you may need to convert these files to the local standard text file format
  18. (for example, if you are on MS-DOS you probably have to convert LF end-of-line
  19. to CR/LF).  If so, apply the conversion to all the files EXCEPT those whose
  20. names begin with "test".  The test files contain binary data; if you change
  21. them in any way then the self-test will give bad results.
  22.  
  23.  
  24. STEP 1: PREPARE A MAKEFILE
  25. ==========================
  26.  
  27. First, select a makefile and copy it to "Makefile" (or whatever your version
  28. of make uses as the default makefile name; for example, "makefile.mak" for
  29. Borland C).  We include several standard makefiles in the distribution:
  30.  
  31.     makefile.ansi: for Unix systems with ANSI-compatible C compilers.
  32.     makefile.unix: for Unix systems with non-ANSI C compilers.
  33.     makefile.mc5:  for Microsoft C 5.x under MS-DOS.
  34.     makefile.mc6:  for Microsoft C 6.x under MS-DOS.
  35.     makefile.tc:   for Borland's Turbo C under MS-DOS.
  36.     makefile.pwc:  for Mix Software's Power C under MS-DOS.
  37.     makefile.manx: for Manx Aztec C on Amigas.
  38.     makefile.sas:  for SAS C on Amigas.
  39.  
  40. If you don't see a makefile for your system, we recommend starting from either
  41. makefile.ansi or makefile.unix, depending on whether your compiler accepts
  42. ANSI C or not.  Actually you should start with makefile.ansi whenever your
  43. compiler supports ANSI-style function definitions; you don't need full ANSI
  44. compatibility.  The difference between the two makefiles is that makefile.unix
  45. preprocesses the source code to convert function definitions to old-style C.
  46. (Our thanks to Peter Deutsch of Aladdin Enterprises for the ansi2knr program.)
  47.  
  48. If you don't know whether your compiler supports ANSI-style function
  49. definitions, then take a look at config.c.  It is a test program that will
  50. help you figure out this fact, as well as some other facts you'll need in
  51. later steps.  You must compile and execute config.c by hand; the makefiles
  52. don't provide any support for this.  config.c may not compile the first try
  53. (in fact, the whole idea is for it to fail if anything is going to).  If you
  54. get compile errors, fix them by editing config.c according to the directions
  55. given in config.c.  Once you get it to run, select a makefile according to the
  56. advice it prints out, and make any other changes it recommends.
  57.  
  58. Look over the selected Makefile and adjust options as needed.  In particular
  59. you may want to change the CC and CFLAGS definitions.  For instance, if you
  60. are using GCC, set CC=gcc.
  61.  
  62. If you are on a system that doesn't use makefiles, you'll need to set up
  63. project files (or whatever you do use) to compile all the source files and
  64. link them into executable files cjpeg and djpeg.  See the file lists in any of
  65. the makefiles to find out which files go into each program (makcjpeg.lst and
  66. makdjpeg.lst are handy summaries).
  67.  
  68.  
  69. STEP 2: EDIT JCONFIG.H
  70. ======================
  71.  
  72. Look over jconfig.h and adjust #defines to reflect the properties of your
  73. system and C compiler.  (If you prefer, you can usually leave jconfig.h
  74. unmodified and add -Dsymbol switches to the Makefile's CFLAGS definition.)
  75.  
  76. If you have an ANSI-compliant C compiler, no changes should be necessary
  77. except perhaps for RIGHT_SHIFT_IS_UNSIGNED and TWO_FILE_COMMANDLINE.  For
  78. older compilers other changes may be needed, depending on what ANSI features
  79. are supported.
  80.  
  81. If you don't know enough about C programming to understand the questions in
  82. jconfig.h, then use config.c to figure out what to change.  (See description
  83. of config.c in step 1.)
  84.  
  85. A note about TWO_FILE_COMMANDLINE: defining this selects the command line
  86. syntax in which the input and output files are both named on the command line.
  87. If it's not defined, the output image goes to standard output, and the input
  88. can optionally come from standard input.  You MUST use two-file style on any
  89. system that doesn't cope well with binary data fed through stdin/stdout; this
  90. is true for most MS-DOS compilers, for example.  If you're not on a Unix
  91. system, it's probably safest to assume you need two-file style.
  92.  
  93.  
  94. STEP 3: MAKE
  95. ============
  96.  
  97. Now you should be able to "make" the software.
  98.  
  99. If you have trouble with missing system include files or inclusion of the
  100. wrong ones, look at jinclude.h (or use config.c, if you are not a C expert).
  101.  
  102. If your compiler complains about big_sarray_control and big_barray_control
  103. being undefined structures, you should be able to shut it up by adding
  104. -DINCOMPLETE_TYPES_BROKEN to CFLAGS (or add #define INCOMPLETE_TYPES_BROKEN
  105. to jconfig.h).
  106.  
  107. There are a fair number of routines that do not use all of their parameters;
  108. some compilers will issue warnings about this, which you can ignore.  Any
  109. other warning deserves investigation.
  110.  
  111.  
  112. STEP 4: TEST
  113. ============
  114.  
  115. As a quick test of functionality we've included three small sample files:
  116.     testorig.jpg    A reduced section of the well-known Lenna picture.
  117.     testimg.ppm    The output of djpeg testorig.jpg
  118.     testimg.jpg    The output of cjpeg testimg.ppm
  119. (The two .jpg files aren't identical since JPEG is lossy.)  If you can
  120. generate duplicates of testimg.ppm and testimg.jpg then you probably have a
  121. working port.
  122.  
  123. With most of the makefiles, "make test" will perform the necessary
  124. comparisons.  If you're using a makefile that doesn't provide this option, run
  125. djpeg and cjpeg to generate testout.ppm and testout.jpg, then compare these to
  126. testimg.* with whatever file comparison tool you have.  The files should be
  127. bit-for-bit identical.
  128.  
  129. NOTE: this is far from an exhaustive test of the JPEG software; some modules,
  130. such as color quantization and GIF I/O, are not exercised at all.  It's just a
  131. quick test to give you some confidence that you haven't missed something
  132. major.
  133.  
  134. If the test passes, you can copy the executable files cjpeg and djpeg to
  135. wherever you normally install programs.  Read the file USAGE to learn more
  136. about using the programs.
  137.  
  138.  
  139. OPTIONAL STUFF
  140. ==============
  141.  
  142. We distribute the software with support for RLE image files (Utah Raster
  143. Toolkit format) disabled, because the RLE support won't compile without the
  144. Utah library.  If you have URT version 3.0, you can enable RLE support as
  145. follows:
  146.     1.  #define RLE_SUPPORTED in jconfig.h or in the Makefile.
  147.     2.  Add a -I option to CFLAGS in the Makefile for the directory
  148.         containing the URT .h files (typically the "include"
  149.         subdirectory of the URT distribution).
  150.     3.  Add -L... -lrle to LDLIBS in the Makefile, where ... specifies
  151.         the directory containing the URT "librle.a" file (typically the
  152.         "lib" subdirectory of the URT distribution).
  153.  
  154. If you want to incorporate the JPEG code as subroutines in a larger program,
  155. we recommend that you make libjpeg.a.  Then use the jconfig.h and jpegdata.h
  156. files as your interface to the JPEG functions, and link libjpeg.a with your
  157. program.  Your surrounding program will have to provide functionality similar
  158. to what's in jcmain.c or jdmain.c, and you may want to replace jerror.c and
  159. possibly other modules depending on your needs.  See the "architecture" file
  160. for more info.  If it seems to you that the system structure doesn't
  161. accommodate what you want to do, please contact the authors.
  162.  
  163. CAUTION: When you use the JPEG code as subroutines, we recommend that you make
  164. any required configuration changes by modifying jconfig.h, not by adding -D
  165. switches to the Makefile.  Otherwise you must be sure to provide the same -D
  166. switches when compiling any program that includes the JPEG .h files.
  167.  
  168. If you need to make a smaller version of the JPEG software, some optional
  169. functions can be removed at compile time.  See the xxx_SUPPORTED #defines in
  170. jconfig.h.  If at all possible, we recommend that you leave in decoder support
  171. for all valid JPEG files, to ensure that you can read anyone's output.
  172. Restricting your encoder, or removing optional functions like block smoothing,
  173. won't hurt compatibility.  Taking out support for image file formats that you
  174. don't use is the most painless way to make the programs smaller.
  175.  
  176.  
  177. NOTES FOR SPECIFIC SYSTEMS
  178. ==========================
  179.  
  180. We welcome reports on changes needed for systems not mentioned here.
  181. Submit 'em to jpeg-info@uunet.uu.net.  Also, config.c is fairly new and not
  182. yet thoroughly tested; if it's wrong about how to configure the JPEG software
  183. for your system, please let us know.
  184.  
  185.  
  186. HP/Apollo DOMAIN:
  187.  
  188. At least in version 10.3.5, the C compiler is ANSI but the system include
  189. files are not.  Use makefile.ansi and add -DNONANSI_INCLUDES to CFLAGS.
  190.  
  191. HP-UX:
  192.  
  193. If you have HP-UX 7.05 or later with the "software development" C compiler,
  194. then you can use makefile.ansi.  Add "-Aa" to the CFLAGS line in the
  195. makefile.  If you have a pre-7.05 system, or if you are using the non-ANSI C
  196. compiler delivered with a minimum HP-UX 8.0 system, then you must use
  197. makefile.unix (and do NOT add -Aa).  Also, adding "-lmalloc" to LDLIBS is
  198. recommended if you have libmalloc.a (it seems not to be present in minimum
  199. 8.0).
  200.  
  201. On HP series 800 machines, the HP C compiler is buggy in revisions prior to
  202. A.08.07.  If you get complaints about "not a typedef name", you'll have to
  203. convert the code to K&R style (i.e., use makefile.unix).
  204.  
  205. IBM RS/6000 AIX:
  206.  
  207. The CFLAGS switch to make the compiler define __STDC__ is "-qlanglvl=ansi".
  208.  
  209. Macintosh Think C:
  210.  
  211. You'll have to prepare project files for cjpeg and djpeg; we don't include
  212. those in the distribution since they are not text files.  The COBJECTS and
  213. DOBJECTS lists in makefile.unix show which files should be included in each
  214. project.  Also add the ANSI and Unix C libraries in a separate segment.  You
  215. may need to divide the JPEG files into more than one segment; you can do this
  216. pretty much as you please.
  217.  
  218. If you have Think C version 5.0 you should be able to just turn on __STDC__
  219. through the compiler switch that enables that.  With version 4.0 you must
  220. manually edit jconfig.h.  (You can #define __STDC__, but also #define const.)
  221.  
  222. Microsoft C for MS-DOS:
  223.  
  224. Some versions of MS C fail with an "out of macro expansion space" error
  225. because they can't cope with the macro TRACEMS8 (defined in jpegdata.h).
  226. If this happens to you, the easiest solution is to change TRACEMS8 to
  227. expand to nothing.  You'll lose the ability to dump out JPEG coefficient
  228. tables with djpeg -d -d, but at least you can compile.
  229.  
  230. Sun:
  231.  
  232. Don't forget to add -DBSD to CFLAGS.  If you are using GCC on SunOS 4.0.1 or
  233. earlier, you will need to add -DNONANSI_INCLUDES to CFLAGS (your compiler may
  234. be ANSI, but your system include files aren't).  I've gotten conflicting
  235. reports on whether this is still necessary on SunOS 4.1 or later.
  236.